docs(automations): bind automation runs to principal authority and receipts - #17

…854) (OpenCoven#861)

Adds one dated status/decision record for issue OpenCoven#854 in docs/superpowers/plans/.

Independently verified against main @ 1364cec (2026-08-30): the coven#816
foundation series (PR OpenCoven#846, PR OpenCoven#847, parts 6-8 commits) landed the durable
local scheduler core - definitions, SQLite definition/occurrence/run records
with unique occurrence fencing, RRULE planning, bounded leases with expiry
recovery, latest-only misfire / overlap refusal, the 60s daemon tick with
scheduled dispatch, shared launch path, health and run history,
non-destructive paused legacy import, and coven.automations.* control
actions. Records what is still absent for v1 (versioned protocol schemas,
authority/receipt binding, deterministic-time contract, SDK surface,
conformance/chaos/SLO gates, live Beads mutation), the gate-by-gate verdict,
and the critical path. The program issue remains open; this record closes
no issue.

Refs OpenCoven#854.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs: point install guidance at canonical coverage

The canonical install, platform, deployment, uninstall, and install-debugging guides are merged in OpenCoven/coven-docs, so the duplicate local pages under docs/install/ become stable pointers per the Wave A cleanup plan. docs/install/development-channels.md keeps its local content because no canonical page covers pre-release channels yet.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs: point onboarding pages at canonical guidance

Duplicate local onboarding pages (quickstart, first session, onboarding, showcase, doctor) become pointers to the canonical getting-started and doctor routes. coven-tui.md keeps its legacy-TUI contract and its root-absolute links are fixed to the retained local session-lifecycle contract and the canonical CLI reference.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs: shrink the README to a landing page and codify the public-docs boundary

The README stops duplicating the canonical manual and keeps the landing-page facts: what Coven is, one install and quick-start path, canonical links, the source-adjacent ownership table, contributor rules, and security. DOCS-MAINTENANCE.md gains the enforceable public-doc directory boundary (canonical pointers or source-adjacent exceptions with stated ownership reasons), and docs/index.md links to it.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* ci: retrigger pull request checks after enabling fork Actions

No file changes. The pull request was opened before Actions was enabled on this fork, so no workflow run was created for its head SHA. This empty commit fires a pull_request synchronize event so the CI matrix can report.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

…Coven#863)

Investigate issue OpenCoven#807 against main at 1364cec (2026-08-30) and record
a dated status/decision document in the repo's record location
(docs/superpowers/plans/).

Facts recorded: the existing non-gating benchmark/chaos corpus, health
and recovery surfaces, release certification (certify-release.sh,
2026-08-29), packaged-artifact journey E2E, release-stress workflow,
and AFS gating posture, each with evidence links and dates; a verdict
against all six acceptance criteria (not satisfied on main; partial on
separation-by-convention, structured receipts, and privacy-by-design);
and a dependency-ordered critical path. No measurements, targets, or
SLOs are invented.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs: record issue 670 docs program status on main

Add a dated status/decision record for OpenCoven#670 at
docs/superpowers/plans/2026-08-30-issue-670-docs-program-status.md.

It records, with evidence links and dates: the merged progressive-help
implementation (OpenCoven#834), the merged packaged first-session E2E (OpenCoven#835,
closing OpenCoven#777), the canonical journey and docs CI live in
OpenCoven/coven-docs (OpenCoven#775/OpenCoven#778 state), the still-open single-source
cleanup of this repository (OpenCoven#776: README shrink, residual local pages,
missing CI ownership enforcement), and the open OpenCoven#779 certification
matrix. It gives a per-criterion verdict against OpenCoven#670's nine acceptance
criteria, what remains, and the critical path.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* chore: retrigger vehicle CI after a dropped pull_request event

The fork vehicle's Actions went live at 2026-08-30T15:54Z, after PR #10
opened at 15:46Z, so the opened/ready_for_review events never started a
run (0 check-runs on the head SHA ~20 minutes after creation). Push an
empty signed commit to fire the synchronize event; no file changes.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* docs: keep issue 670 record clear of the privacy phone detector

The Coven privacy guard's phone_number rule (E.164-like plus-digit
tokens) flags the diff-stat notation (+1828), (+464), (+279), (+323),
and (+2686) in the OpenCoven#670 status record. Restate those as insertion and
deletion counts; no content changes.

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* test(agents): characterize input-guardrail ingress at handoff boundaries

Characterizes the coven-agents runner's input-guardrail behavior so the
handoff bypass in OpenCoven#803 is visible from test output before
the enforcement change:

- direct-entry rejection vs handoff entry to the same target (parity
  regression: currently the handoff target's input guardrails never run)
- handoff target GuardrailChecked event ordering (after Handoff, before
  the target's first ModelRequested) and the exact evaluated input
- multi-hop A->B->C per-boundary checks and a target rejection at hop C
- input-guardrail implementation error vs policy rejection, direct and
  handoff (GuardrailFailed keeps its own message and source)
- handoff/tool action exclusivity stays pinned

Tests encode the corrected expectation and are paired with the runner
change in the next commit; compile proof and green runs defer to CI
(this workspace has no Rust toolchain).

Refs OpenCoven#803

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* fix(agents): enforce target input-guardrail parity across handoffs

Closes the ingress bypass in Runner::run_loop (OpenCoven#803): a
handoff target's input guardrails were never evaluated, so an agent
reached through a model handoff could consume input that direct entry
to it would reject.

- extract the input-guardrail evaluation into one shared path,
  Runner::check_input_guardrails, used by direct starts and by every
  handoff boundary
- evaluate the handoff target's input guardrails against the original
  user input — the same bounded string a direct start would check,
  never a serialized transcript — after the Handoff item/event is
  recorded and before the target's first model turn or tool execution
- a target rejection or guardrail implementation error fails the run
  (RunFailureKind::InputGuardrail) before the target's model call, so
  the target receives no model request and executes no tool; the
  GuardrailFailed/GuardrailRejected distinction is preserved
- emit GuardrailChecked with the target identity and Input stage;
  exactly one terminal RunCompleted/RunFailed pairing is preserved
- multi-hop A->B->C now applies each hop's ingress policy at its own
  boundary

Documented compatibility contract: target ingress is evaluated over the
original/root user input only. The structured task/context manifest for
delegated invocations is the successor contract in
OpenCoven#804; this patch is not complete A2A security.

Handoff/tool exclusivity, fail-fast topology validation, handoff
limits, session semantics, and output-guardrail behavior are unchanged.

cargo fmt/clippy/test verification defers to CI (no Rust toolchain in
this workspace); formatting verified with a standalone rustfmt binary.

Refs OpenCoven#803
Refs OpenCoven#804

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* fix: keep handoff checks warning-free

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

Issue OpenCoven#774 asks Coven to keep default help concise, preserve every
command through the grouped `coven help --all` view, and expose a
deterministic JSON help contract. The executable side of that work
landed in OpenCoven#834; the contract itself remained undocumented for
consumers.

Document the contract in the developer core-functionality guide
(schemaVersion 1 payload shape, determinism and leak guarantees,
drift-fails-loudly rule) and surface it to script authors in the
automation JSON guide. Extend scripts/cli-docs-test.mjs so the docs
guard fails when the contract documentation regresses.

Refs OpenCoven#774

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

…es, and changefeed

Publish the coven.automations.v1 contract as spec artifacts plus a normative
design document, so Cave, the SDK, Psyche adapters, runtimes, and future
implementations can consume automations without importing Coven internals.

spec/coven-automations/v1/ (draft 2020-12 JSON Schemas and machine-readable
artifacts, following the spec/device-pairing/v1 precedent):
- five object schemas (definition, occurrence, run, attempt, receipt) with
  monotonic revisions, integrity digests, exact-revision pinning, and
  fail-closed unknown-field behavior through an explicit extension bag
- command/response envelope: every mutating command carries a stable
  adoption key (first-commit-wins replay, ADOPTION_REPLAY_MISMATCH on
  conflict) and expectedRevision where applicable; responses are
  committed/replayed/rejected only, so a domain failure can never be
  wrapped as accepted
- typed error envelope with a frozen HTTP/control-action status mapping
- versioned changefeed envelope: per-stream gapless sequences, globally
  unique event ids, causation, cursor expiry, compaction snapshots
- state-machines.json: authoritative definition/occurrence/run/attempt
  machines plus the ten normative invariants
- capabilities.json: positive and explicit negative variant negotiation
- compatibility-matrix.json: change classes and profile-refusal rules
- test-vectors.json: golden valid/invalid/unknown-field/downgrade/
  unknown-variant vectors, adoption replay and revision-conflict cases,
  duplicate and out-of-order event replay, with pinned RFC 8785 digests
- coven.automations.v1.d.ts: pinned TypeScript projection for SDK/Cave
  canaries

docs/architecture/coven-automations-v1.md: the design document, citing the
current OpenCoven#816 code paths for every gap, ratifying the lifecycle semantics,
the OpenCoven#816 non-destructive migration, the Rust type mapping, and recording
alternatives considered for the genuinely maintainer-owned decisions.

No runtime code changes: schemas, vectors, and docs only.

Refs OpenCoven#855

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* refactor: extract route/version authority gate from coven-cli api

Move ApiRoute, normalize_api_route, split_path_query, and the
route-version constants out of the 25k-line api.rs into a dedicated
api_routes.rs gate module (issue OpenCoven#806 slice 1: extract pure
request/route parsing first, behind stable contracts).

- the gate keeps its exact contract: non-/api/ paths pass through
  borrowed, /api/v1/<route> is rewritten to /<route>, unsupported
  versions answer 404 invalid_request with the apiVersion and
  supportedApiVersions payload, other malformed /api/... shapes
  answer 404 not_found
- characterize the pure classifier (positive, malformed, unsupported,
  passthrough, query-splitting, version-prefix-never-retained
  property) and pin the full unsupported-version rejection envelope
  plus the uniform 404 envelope for malformed API prefixes through
  handle_request
- document the authority-direction invariant on the gate and publish
  the concentration inventory, extraction order, and
  where-new-behavior-belongs map in docs/authority-module-inventory.md

No behavior change: handlers, routes, status codes, error envelopes,
payloads, and persistence are untouched.

Refs OpenCoven#806

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

* chore: format authority gate test

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

---------

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>

…ceipts

Specify the AutomationExecutionBinding contract (coven.automation_execution_
binding.v1) that makes automation dispatch normative: authenticated principal
authority, exact familiar root/revision/declaration-digest binding, per-run
Threads authorization, operation-specific capability grants, an approval
lifecycle that is bounded and replay-safe, R0-R4 side-effect classes with
safe unattended defaults, and a verifiable AutomationReceipt committed on
every terminal run.

PRODUCT.md carries the normative contract; TECH.md maps it onto the landed
coven#816 automations foundation (definition/occurrence/runner/runs ledger),
the Psyche execution-binding and request-adoption seams, the threads authority
gate, and the privacy/encryption primitives, and lays out the trait seams,
schema deltas, threat-vector test matrix, and delivery slices.

Refs OpenCoven#857

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
Signed-off-by: CompleteDotTech <5861166+CompleteDotTech@users.noreply.github.com>